Instructions for use of the Popup Menu XObject 2.0

Written by Scott Kildall

Copyright © 1995, Red Eye Software. All Rights Reserved.

Licensing the Popup XObject

This is a demo version of the Popup XObject which is fully functional except that each time you try to activate a popup menu, a dialog box indicating that this is an unregistered copy will get displayed. This can be bypassed by holding down the control key.

To prevent the dialog box from being displayed, you will need to license the XObject from Red Eye Software. The licensing fees if $300/company for both the Macintosh and the Windows version of the XObject. This gives the company an UNLIMITED right to distribute it with any product it creates.

All you need to do is fax or send me the licensing agreements from the file "LICENSE.RTF". I will then immediately e-mail you serial numbers which can be used with the mRegister method to "unlock" the XObject. Payment should then be made from 30 days after receiving the serial numbers from me.

When filling out the licensing agreements, please be sure to include ALL of the information about you company especially the your e-mail address and your fax number.

You can reach me by the following means:

E-mail:
kildall@eskimo.com
kildall@aol.com
72703.451@compuserve.com

website: http://www.eskimo.com/~kildall

Regular mail:
Red Eye Software
1516 Second Ave., Suite 300
Seattle, WA 98101

Fax:
fax: 206-624-9866

Using the Popup XObject

Concepts:

The Menu List
In all of the method descriptions below, a string parameter called <menuList> describes a menu items or menu with optional hierarchical items to be built. The notation for this is:

-> A return or semi-colon character (;) is used to separate menu items
-> A left brace character ([) is used to indicate that this menu item has a submenu attached to it and a right brace character (]) indicates that the submenu definition is finished. Between the brace characters should be the submenu items.

Examples:

(1) A menu list of “Fred;Joe;Bob” will create one menu with 3 items on it (Fred, Joe and Bob). Return characters could be used instead of the semi-colons which becomes useful when items are located inside a text field.

(2) A menu list of “Cats;Dogs[Dalmatians;St. Bernards];Reptiles[Iguanas;Turtles; Monitor Lizards] will result in a main menu with three items (Cats, Dogs, Lizards). Attached to item #2 (Dogs) will be a submenu with two items (Dalmatians and St. Bernards). Attached to item #3 (Reptiles) will be a submenu with three items (Iguanas, Turtles and Monitor Lizards).

The menu list is prepared to try to account for potential errors. Empty menu items will not be added to the menu. The internal parser will attempt to rectify other errors where possible.

The Menu Spec
The menu specification is a string of numbers indicating a particular menu item, denoted in the description below by a <menuSpec>. This will be returned by mPopupSpec and will also passed as a parameter to a number of the methods.

How to activate the popup menu
The popup menu can be activated by one of two functions, mPopupSpec and mPopupNum. These should always be called on a mouseDown script.

Error numbers:

Error numbers are always negative and the following error numbers may be generated. If a method returns an error of zero, then it indicates that no error has occurred.

Error Number		Meaning
	-1			Out of memory
	-2			Can’t find menu
	-3			Invalid parameters were passed in by the user
	-4			This is not a valid menu item
	-5			Internal error (Macintosh only)
	-6			Text is too long
	-7			Invalid mark type
	-8			This is a submenu
	-9			Internal error
	-10			Invalid item style
	-11			Invalid color parameters
	-12			Empty menu list
	-13			Ran out of menus
	-14			Internal error (Windows)

You should hopefully never receive any of the internal errors.

Methods:

mNew( string menuList )

Parameters:
<menuList>: a string describing the menus that will initially be created (see menu list description above).

Note: this can be an empty string ("") in which case the XObject will be allocated but a menu will not be activated. Menu items can later be added with mAppendMenu.

This creates an instance of the Popup XObject.

mDispose()

Parameters: None
Returns: An error code

This disposes of an instance of the XObject.

Error codes that may be returned:

Error Number		Meaning
	0		No error

This releases an instance of the Popup XObject from memory.

mRegister( string <serial number> )

Returns: Nothing
Parameters: A string indicating the serial number

The mRegister method is for companies which have licensed the XObject and removes the "unregistered" dialog box. This method should be called immediately after mNew.

Example scripts:

on initializeXObject
	global gPopupObj 
	--where gPopupObj will be an instance of Popup XObject
	
	-- dispose of any previous instances
	if objectP(gPopupObj ) then gPopupObj (mDispose)

	set gPopupObj = Popup(mNew, "Item 1;Item 2;Item 3")

	if( gPopupObj ) then

		-- Register the Windows version
		if the machineType = 256 then gPopupObj (mRegister, "??? Windows" )

		-- Register the Macintosh version
		else gPopupObj (mRegister, "??? Macintosh" )
	
	end if

end initializeXObject

• Substitute your serial number for the one with the question marks.

mName()

Parameters: None
Returns: A string indicating the name of the XObject

This returns the name of the XObject.

mAppendItem( string menuList, string menuSpec )

Parameters:
<menuList>: A menu item (plus any submenus) that will be added to the end of the menu specified by the menuSpec.

<menuSpec>: The menu to which a menu item will be appended.

Returns: An error code

This will add a menu item and any submenus to a menu. The menu does not have to be the main menu.

Note: The menu spec must contain a menu item just like mInsertMenu below. The item number will be ignored.

mInsertItem( string menuList, string menuSpec )

Parameters:
<menuList>: A menu item (plus any submenus) that will be added to the end of the menu specified by the menuSpec.

<menuSpec>: The menu to which a menu item will be appended.

Returns: An error code

This will add a menu item and any submenus to a menu. The menu does not have to be the main menu. It will be inserted before the specified menu item. 

Example:

set errNum = gPopupObj(mInsertMenu, “Evil Figures[Satan;Bono;Caligula]”, “3”)

This will insert a menu item called “Evil Figures” with a submenu of 3 items (Satan, Bono and Caligula) before item #3 in the main menu.

set errNum = gPopupObj(mInsertMenu, “Mussolini”, “3;2”)

This will insert an item called “Mussolini” before “Bono”)

mDeleteItem( string menuSpec )

Parameters:

<menuSpec>: A menu item which will be deleted

Returns: An error code

This will delete a menu item and any of its submenus.

Example

set errNum = gPopupObj(mDeleteItem, “2;1”)

This will delete the first item off of the submenu attached to item #2.

mDisabletem( string menuSpec )

Parameters:

<menuSpec>: A menu item which will be disabled

Returns: An error code

This will disable a menu item and any of its submenus.

mEnableItem( string menuSpec )

Parameters:

<menuSpec>: A menu item which will be enabled

Returns: An error code

This will enabled a menu item.

mGetItem( string menuSpec )

Parameters:

<menuSpec>: A menu item to get the text for

Returns: The text of a menu item. This will be an empty string if the menuSpec is invalid.

mSetItem( string menuSpec, string itemText )

Parameters:

<menuSpec>: A menu item which will be enabled

<itemText>: The text of a menu item. If it is more than 255 characters, then it will be truncated.

Returns: An error code

This will change the name of a menu item.

mPopupSpec( long left, long top, [long alignmentItem] )

Parameters:

<left>: The left position (relative to the stage/current MIAW) when the menu shall appear.

<top>: The top position (relative to the stage/current MIAW) when the menu shall appear.

<alignmentItem>: Optional parameter. This is an item number to which the popup menu will automatically align itself. Pass the currently selected item number here to follow the Macintosh standard interface guidelines.

Returns: An error code

This will activate the popup menu and should be called on a mousedown, returning the text of the item selected, an empty string if the pulled off of the menu.

Note: This should always be activated from a on mouseDown script

Trick: To get the item number of the main menu that was selected, you can use the Lingo's value function such as:

set result = gPopupObj(mPopupSpec, the left of sprite 1, the top of sprite 1)

if result <> ""
    --- something was selected
    set selectedItemNum = value(result)
end if

mPopupText( long left, long top, [long alignmentItem] )

Parameters:

<left>: The left position (relative to the stage/current MIAW) when the menu shall appear.

<top>: The top position (relative to the stage/current MIAW) when the menu shall appear.

<alignmentItem>: Optional parameter. This is an item number to which the popup menu will automatically align itself. Pass the currently selected item number here to follow the Macintosh standard interface guidelines.

Returns: An error code

This will activate the poup menu and should be called on a mousedown, returning the text of the item selected, an empty string if the pulled off of the menu.

Note: This should always be activated from a on mouseDown script

mSetItemMark( string menuSpec, integer markNumber )

Parameters:

<menuSpec>: A menu item to set the mark (e.g. a checkmark) for

<markNumber>: A mark to be placed next to a menu item

Returns: An error code

This will place a mark such as a check next to a menu item. If the XObject is automatically marking the item (see mSetAutoMark below), this will remove the mark a previously marked item on that menu.

The mark numbers are as follows

Mark Number		Meaning
	0		No mark (removes any marks)
	1		Check
	2		Black diamond
	3		Apple
	4		Command symbol
	5		Bullet
	6		Check (serif font)
	7		Prompt symbol
	8		Open diamond

Note: Windows only supports check marks and so passing any value from 1-8 will map to a check mark under Windows.

mSetAutoMark( trueOrFalse autoMarkItems, [integer markNumber ])

Parameters:

<autoMarkItems>: True if auto-marking should be on and false if not.

<markNumber>: Optional, a mark number to be used (see list above). This can only be used if autoMarkItems is true.

Returns: An error code

When the XObject is set to auto-mark items, it will place a mark (whatever was last specified in mSetAutoMark) next to the last selected item. By default, auto-marking is on and the checkmark is the mark type.

mSetItemStyle( string menuSpec, integer styleType )

Parameters:

<menuSpec>: A menu item to be changed

<styleType>: A font style or combination of styles to be applied to the menu item.

Returns: An error code

This will change the font style (e.g. plain text, bold , italic) of a menu item a combination of styles may be used

The style numbers are as follows:

Style Number		Meaning
	0		plain text
	1		bold
	2		italic
	4		underline
	8		outline
	16		shadow
	32		condensed text
	64		extended text

Examples:

gPopupObj(mSetItemStyle, “3”, 1)

This make item #3 show up in bold.

gPopupObj(mSetItemStyle, “6”, 1 + 2 + 64)

This make item #6 show up in bold, italicized, extended text (eech!).

Note: Windows does not support this function. The method is in the Windows version of the XObject but will always return a value of zero.

mSetForegroundColor( integer index )
mSetForegroundColor( integer redColor, blueColor, greenColor )

Note: this function takes two different forms

Parameters:

(form 1)
<index>: An indexed color from the palette to be used as the menu text color for all of the menus. This should be in the range of 0-255. Calling it when the color depth is greater than 8 will result in strange and unpredictable colors.

(form 2, recommended)
<redColor>: A value for the red channel of an RGB color, in the range of 0-255
<blue Color>: A value for the green channel of an RGB color, in the range of 0-255
<green Color>: A value for the blue channel of an RGB color, in the range of 0-255

Returns: An error code

This will change the color used for the text of menus.

Examples:

gPopupObj(mSetForegroundColor( 255, 0, 0 )

This makes all of the menu text red.

Note: Unfortunately, Windows does not support this function and there is little I can do about it. Bad Windows, bad Windows.

mSetForegroundColor( integer index )
mSetForegroundColor( integer redColor, blueColor, greenColor )

Note: this function takes two different forms

Parameters:

(form 1)
<index>: An indexed color from the palette to be used as the background color for all of the menus. This should be in the range of 0-255. Calling it when the color depth is greater than 8 will result in strange and unpredictable colors.

(form 2, recommended)
<redColor>: A value for the red channel of an RGB color, in the range of 0-255
<blue Color>: A value for the green channel of an RGB color, in the range of 0-255
<green Color>: A value for the blue channel of an RGB color, in the range of 0-255

Returns: An error code

This will change the color used for the text of menus.

Examples:

gPopupObj(mSetBackgroundColor( 0, 0, 0 )

This makes the background of all of the menus black

Note: Unfortunately, Windows does not support this function and there is little I can do about it.

Compatibility Issues and Limitations:

• Windows does not support automatic scrolling of menu items and so more than 23 items will not fit on a standard screen. If you have more than 23 items to choose from, I would suggest separating them into hierarchical menu items.